EnvironmentValuesReader#

EnvironmentValuesReader 是 Scripting 提供的一个组件，用于读取 SwiftUI 风格的环境值（Environment Values）。 它允许脚本在视图层级中访问当前环境的上下文信息，例如颜色模式、尺寸类别、是否正在搜索、是否被呈现、编辑模式等。

该组件的定位与 SwiftUI 中的 @Environment 类似，但设计上更加明确： 你必须指定要读取的 environment keys，系统仅在渲染时读取这些值并传入回调函数。

EnvironmentValues 类型#

1type EnvironmentValues = {
2    colorScheme: ColorScheme;
3    colorSchemeContrast: ColorSchemeContrast;
4    displayScale: number;
5    horizontalSizeClass: UserInterfaceSizeClass | null;
6    verticalSizeClass: UserInterfaceSizeClass | null;
7    dismiss: () => void;
8    dismissSearch: () => void;
9    editMode: EditMode | null;
10    widgetRenderingMode: WidgetRenderingMode;
11    showsWidgetContainerBackground: boolean;
12    isSearching: boolean;
13    isPresented: boolean;
14};

以下为每个字段的说明：

字段说明#

1. colorScheme#

类型：ColorScheme 说明：当前系统的颜色模式，例如 light 或 dark。

2. colorSchemeContrast#

类型：ColorSchemeContrast 说明：颜色对比度模式，例如 standard、increased。

3. displayScale#

类型：number 说明：设备屏幕的像素缩放比例，例如 2.0, 3.0。

4. horizontalSizeClass#

类型：UserInterfaceSizeClass | null 说明：横向尺寸类别，可用于响应式布局。 可能值：compact / regular。

5. verticalSizeClass#

类型：UserInterfaceSizeClass | null 说明：纵向尺寸类别，行为同上。

6. dismiss#

类型：() => void 说明：用于关闭当前呈现的界面，等价于 SwiftUI 的 dismiss()。

7. dismissSearch#

类型：() => void 说明：关闭当前的搜索 UI（如果 searchable 处于激活状态）。

8. editMode#

类型：EditMode | null 说明：当前视图是否处于编辑模式（例如 List 的编辑状态）。

9. widgetRenderingMode#

类型：WidgetRenderingMode 说明：Widget 渲染模式，例如 fullColor、accented 等。

10. showsWidgetContainerBackground#

类型：boolean 说明：指示 widget 是否显示系统容器背景。

11. isSearching#

类型：boolean 说明：当前 view 是否处于搜索状态（来自 searchable）。

12. isPresented#

类型：boolean 说明：当前 view 是否已呈现，和 onAppear 回调不同，不像 onAppear 会多次触发。

EnvironmentValuesReader 组件#

1type EnvironmentValuesReaderProps = {
2    /**
3     * The keys to read from the environment values.
4     */
5    keys: Array<keyof EnvironmentValues>;
6    /**
7     * The callback function to render the children, it will be called with the environment values.
8     */
9    children: (values: EnvironmentValues) => VirtualNode;
10};

Props 说明#

keys#

类型：Array<keyof EnvironmentValues> 说明：指定需要读取的 environment key 列表。

只有指定的 key 才会被 read 并传入 children。

children(values)#

类型：(values: EnvironmentValues) => VirtualNode 说明：用于渲染子节点的回调。 系统会收集你请求的 environment key，并将其值合并成一个对象传入。

组件定义#

1declare const EnvironmentValuesReader: FunctionComponent<EnvironmentValuesReaderProps>;

使用示例#

示例：读取 colorScheme 和 displayScale#

1import { EnvironmentValuesReader, Text, VStack } from "scripting"
2
3function View() {
4  return <EnvironmentValuesReader
5    keys={["colorScheme", "displayScale"]}
6  >
7    {(env) => {
8      return <VStack>
9        <Text>Color Scheme: {env.colorScheme}</Text>
10        <Text>Scale: {env.displayScale}</Text>
11      </VStack>
12    }}
13  </EnvironmentValuesReader>
14}

示例：读取 dismiss#

1<EnvironmentValuesReader keys={["dismiss"]}>
2  {(env) => {
3    return <Button
4      title="Close"
5      action={() => env.dismiss()}
6    />
7  }}
8</EnvironmentValuesReader>

示例：根据 sizeClass 动态布局#

1<EnvironmentValuesReader keys={["horizontalSizeClass"]}>
2  {(env) => {
3    const compact = env.horizontalSizeClass === "compact"
4    return compact ? <Text>Compact Layout</Text> : <Text>Regular Layout</Text>
5  }}
6</EnvironmentValuesReader>

使用注意事项#

1. 必须显式指定 keys，否则不会读取任何 environment 值。
2. 每次所指定的 environment key 发生变化时，children() 会重新渲染。
3. dismiss 和 dismissSearch 是实际可调用的操作，与 SwiftUI 一致。
4. environment 的来源来自父视图树，包括 Navigation, searchable, editMode, Widget 等组件。
5. 未在 keys 中声明的字段不会出现在 values 对象中。
6. 不用于替代全局状态，适用于读取系统环境或父组件传递的上下文信息。